Apple IIgs Technote #53 - Desk Accessories and Tools
Apple Developer Technical Support
Copyright (c) 1990 Apple Users' Group, Sydney
Republished from Applecations, a publication of the Apple Users' Group, Sydney, Australia.
Apple II
Technical Notes
______________________________________________________________________________
Developer Technical Support
Apple IIGS
#53: Desk Accessories and Tools
Revised by: Dave Lyons November 1989
Written by: Matt Deatherage & Jim Mensch March 1989
This Technical Note describes new guidelines for developers to help
applications and desk accessories live together in the same system at the same
time.
Changes since March 1989: Added additional discussion and minor
revisions; corrected tool set numbers for Event Manager and QuickDraw
Auxiliary.
______________________________________________________________________________
Desk accessories vary widely in complexity. Classic Desk Accessories (CDAs)
range from simple status-reporting programs to complete system-level debugging
utilities, and similarly, New Desk Accessories (NDAs) range from static
windows with pictures to nearly full-fledged applications.
This Note presents some new guidelines aimed at helping developers of both
applications and desk accessories to get their products to work together now
and in the future.
Tool Sets
The greatest conflict between applications and desk accessories, especially
NDAs, is the use of system tool sets. The Apple IIGS Toolbox Reference,
Volume 1, defines which tools are available for use by NDAs. The Desk Manager
requires starting the following tool sets before calling FixAppleMenu (which
installs the names of the NDAs in the Apple menu):
Tool Locator (#1)
Memory Manager (#2)
Miscellaneous Tools (#3)
QuickDraw II (#4)
Event Manager (#6)
Window Manager (#14)
Menu Manager (#15)
Control Manager (#16)
LineEdit (#20)
Dialog Manager (#21)
Scrap Manager (#22)
Since the Desk Manager requires starting these tools before calling
FixAppleMenu, NDAs may assume that these tools are all present and running, so
they do not need to check for their presence. In addition to these
requirements by the Desk Manager, Apple strongly recommends that all
applications start the following tools:
QuickDraw Auxiliary (#18)
Font Manager (#27)
These two additional tools are so widely used by desk accessories that they
should be present. NDAs may not assume their presence, but it is reasonable
to write an NDA that checks for them, with the assumption that they will
usually turn out to be available.
The Golden NDA Guideline
Developers who wish to maintain maximum compatibility between their NDAs and
applications, both now and in the future, should consider every environment
change they make with the following Golden NDA Guideline firmly in mind:
"I, an NDA, pledge not to alter the environment of the application
under which I run, and I will behave in such a way that the
application runs the same whether I am present or not."
Of course, this guideline does not include such necessary tasks as the normal
(and reasonable) allocation of memory. An application must be prepared to
handle a memory allocation call by a desk accessory, operating system, or even
a tool at unexpected times. The guideline does, however, mean that your desk
accessory cannot change the operating environment, including such things as
the presence of tools and operating system parameters. The following sections
detail some of the most important ways to follow the Golden NDA Guideline.
Desk Accessory Guidelines
Extra Tools
o If an NDA needs to use a tool which is not guaranteed to be available
(e.g., Standard File), it should check to see if the tool is already
running. If it is not running, the NDA must use LoadOneTool to load it,
then it must start the tool before using it. When finished with the
tool, the NDA must shut it down and unload it with UnloadOneTool. (A
tool is already running if its xxxStatus function returns TRUE and no
error.)
o If an NDA needs to start up a tool and keep it started while letting
the application continue to run, things quickly get complicated.
The Golden NDA Guideline shows why this is true. If your NDA starts a
tool which the application is going to use but has not yet started
(i.e., the Font Manager), and your NDA does not shut it down before the
application regains control, the application will (in this example) get
error $1B01 (Font Manager Already Started) when it makes an FMStartUp
call. Many applications stop gracelessly on getting a tool startup
error.
In this case, the Golden NDA Guideline means that an application must
not be forced to check the status of a tool which it has not started.
Applications are not required to do so, and most of them do not.
A previous version of this Note advised NDAs to start up and shut down
tools when their windows were activated and deactivated. This approach
isn't strong enough to solve all the problems, since the application may
decide to start up tools based on menu items (which can still be
selected while an NDA window is in front).
The only completely safe way to use a tool that isn't already running is
to start it, use it, and shut it back down without ever returning
control to the application while the tool set is started.
Starting QuickDraw Auxiliary when the application has not started it can
get you into a lot of trouble: an application that correctly implements
320/640 mode switching will call QDShutDown and QDStartUp. QuickDraw
Auxiliary depends heavily on QuickDraw, and restarting QuickDraw while
QuickDraw Auxiliary is active will easily toast you.
o If your NDA allocates bank-zero work area space for tool sets, be sure
to dispose of it at DeskShutDown time (when your DAInit entry is called
for shutdown). If you don't, the system will die with error $0201 when
trying to launch a ProDOS 8 application, since GS/OS needs all of banks
0 and 1 to start ProDOS 8.
o Sound tools provide the one exception to the rule of freely using a tool
which is already started. Refer to the section on System Parameters for
more details on using sound tools.
o NDAs must not shut down tools which they have not started.
o CDAs are nearly always modal, but by using the HeartBeat interrupt queue
or other mechanisms, they can get control when the user is no longer
"in" the CDA. The list of guaranteed tools for NDAs does not apply to
CDAs, and CDAs must be prepared to deal with the ProDOS 8 environment as
well as GS/OS.
System Parameters
o A desk accessory (CDA or NDA) must not change a system resource or
parameter which cannot be restored to its original condition. A
trivial, but illustrative, example of this is the number of times a
pull-down menu item blinks when you select it. This number (three by
default) may be changed with the SetMItemBlink call, but there is no
corresponding GetMItemBlink call, so you cannot retrieve the current
value. Therefore, a desk accessory must not change this parameter, and
the same rule applies to any other system parameter for which you cannot
determine a current value.
o This idea extends to calling tool startup functions. Even though a
tool's startup function may not return an error when the tool is already
active, the startup function could reset certain parameters upon which
the application depends. An example of this is TLStartUp for the Tool
Locator. A seemingly innocuous call, TLStartUp actually disconnects any
user tool sets present, which, in this case, would most likely have been
installed by the current application. CDAs and NDAs must never call
TLStartUp or TLShutDown.
A desk accessory should not call any tool's startup function if the tool
is already active. The one exception to this rule is the Memory
Manager's MMStartUp call, which a desk accessory may make to obtain its
User ID. Think of MMStartUp as a "GetMyID" call.
o A desk accessory cannot use any of the sound tools if they are already
started. This is contrary to the rule for other tool sets, but it is
required because there is no memory management of the sound RAM (or "DOC
RAM"). If the Sound Tools (#8) are started, the application has
exclusive control of the 64K DOC RAM used to play sounds. Anything your
desk accessory might put there could overwrite information the
application needs.
Saving and restoring DOC RAM around desk accessory usage is not
sufficient. Many of the sound functions are interrupt driven, altering
the contents of DOC RAM only during sound interrupts, so your desk
accessory might attempt to replace parts of DOC RAM which are being
played. Since there is no memory management of DOC RAM, desk
accessories must avoid the sound functions of the IIGS if the
application is already using them.
o A desk accessory must not install user tool sets, because there is no
arbitration of user tool set numbers. User tool sets are the sole
property of the current application.
Application Guidelines
To coexist peacefully with desk accessories, particularly NDAs, applications
generally need to follow the guidelines listed in the Desk Manager chapter of
the Apple IIGS Toolbox Reference, Volume 1. However, those applications which
wish to ensure maximum compatibility now and in the future will also want to
adhere to the following:
o Don't just start the Scrap Manager--use it. Many desk accessories
support cutting and pasting to exchange text and pictures with your
application, but they can do it only if you use the Scrap Manager. If
you have a need for your own private scrap internally, you should still
also use the Scrap Manager to exchange text and pictures with other
applications and DAs.
o Start tools at the beginning of your application and leave them started.
Every time you call SystemTask or TaskMaster, a desk accessory may get
control of the system, and if your application has shut down a tool that
a desk accessory found running and is using, the DA might not be able to
complete an operation.
For maximum compatibility, do not shut down any tools which were ever
active when you called SystemTask or TaskMaster. You can start more
tools, but do not shut down those which are already active. If you
intend to start a tool and not keep it started, use it then shut it down
immediately, being sure not to call SystemTask or TaskMaster during that
time.
o Applications should not call CloseAllNDAs while shutting down. Since
DeskShutDown closes all open NDAs anyway, it's not necessary. By not
calling CloseAllNDAs, you allow the system or NDAs to tell the
difference between just cleaning up and really wanting to close all
the NDAs.
o Applications should never make a Close call with reference number zero
at file level zero. (If you need to use Close with reference number
zero, use GetLevel and SetLevel to avoid closing files you did not
open.)
o An application with some memory to spare can save NDAs time by providing
them the additional tools which they are most likely to use. If a desk
accessory needs the List Manager and your application starts it, the
desk accessory will run faster since it can avoid loading and starting
the tool every time it gets control.
The most common tools which desk accessories require besides those
available in the standard Desk Manager set are QuickDraw Auxiliary
(#18), the Print Manager (#19), Standard File (#23), the Font Manager
(#27), and the List Manager (#28). QuickDraw Auxiliary and the Font
Manager are especially important--not only do they work well together,
but they are also widely used. In addition, FMStartUp can take a long
time, and waiting for it every time you activate an NDA window can be
really frustrating. Many desk accessories also use the Print Manager,
the List Manager, and Standard File, and if they are always available,
desk accessories will work more smoothly with your application.
Further Reference:
______________________________________________________________________________
o Apple IIGS Toolbox Reference, Volume 1
o Programmer's Introduction to the Apple IIGS

THIS CONTENT COPYRIGHT © 2007, APPLE MACINTOSH USERS' GROUP, SYDNEY
Permission has been obtained to make this material available on the Internet.

Permission is hereby granted for non-profit user groups to republish this content.
PLEASE CREDIT THE AUTHOR AND THE SOURCE: Applecations, publication of the Apple Users' Group, Sydney, Australia

THIS PAGE COPYRIGHT © 2007, ANDREW ROUGHAN